Amazon Aurora Serverless v2 has been available for a while and has proven to be a cost-effective option for certain types of workloads. AWS SAM, as an extension of CloudFormation, can be used to create resources beyond Lambda functions, such as databases. In this article, we will delve into the process of using AWS SAM to create our Amazon Aurora Serverless v2 database.
Pre-requisites
We will require at least four resources, assuming we already have a VPC.
DB Subnet Group
A DB subnet group is a collection of subnets that you create in a VPC and that you then designate for your DB instances:
DBSubnetGroup:
Type: AWS::RDS::DBSubnetGroup
Properties:
DBSubnetGroupDescription: Aurora DB subnet group
SubnetIds:
- <MY_SUBNET_1>
- <MY_SUBNET_2>
The only requirement is that we must specify two or more subnets located in at least two availability zones.
VPC Security Group
A VPC security group is required to control inbound and outbound traffic to the DB instance:
DBSecurityGroup:
Type: AWS::EC2::SecurityGroup
Properties:
GroupName: Aurora DB SG
GroupDescription: Ingress rules for Aurora DB
VpcId: <MY_VPC>
SecurityGroupIngress:
- IpProtocol: tcp
FromPort: 5432
ToPort: 5432
CidrIp: 0.0.0.0/0
In our case, we define an inbound rule that allows access from any source IP to port 5432.
Always aim to make your ingress rules as restrictive as possible. The current configuration is for testing purposes only.
DB Cluster
An Amazon Aurora DB cluster consists of a DB instance and a cluster volume that holds the data for the DB cluster:
DBCluster:
Type: AWS::RDS::DBCluster
DeletionPolicy: Delete
Properties:
DatabaseName: mydatabase
DBClusterIdentifier: my-dbcluster
DBSubnetGroupName: !Ref DBSubnetGroup
VpcSecurityGroupIds:
- !Ref DBSecurityGroup
Engine: aurora-postgresql
EngineVersion: 15.4
MasterUsername: <MY_USER>
MasterUserPassword: <MY_PASSWORD>
Port: 5432
ServerlessV2ScalingConfiguration:
MaxCapacity: 1.0
MinCapacity: 0.5
The DeletionPolicy set to Delete will remove the resource and all its content, if applicable, during stack deletion. The current configuration is for testing purposes only. For more information, please refer to the following documentation.
The properties defined in the cluster are:
DatabaseName: The name of our initial database, which only accepts alphanumeric characters in the case of the PostgreSQL engine.
DBClusterIdentifier: The cluster identifier must contain from 1 to 63 letters, numbers, or hyphens.
DBSubnetGroupName: The reference to the DB subnet group previously created.
VpcSecurityGroupIds: The reference to the VPC security group previously created.
Engine: The name of the database engine to be used for the DB cluster, with aurora-mysql and aurora-postgresql as serverless options.
EngineVersion: The version number of the database engine to use. We can list all available options by running the command aws rds describe-db-engine-versions --engine <MY_ENGINE> --query '*[].[EngineVersion]' --output text --region <MY_REGION>.
MasterUsername: The name of the master user for the DB cluster.
MasterUserPassword: The master password for the DB instance. It can include any printable ASCII character except /, ', ", @, or a space.
Port: The port number on which the DB instances in the DB cluster accept connections. Since we are not setting up an EngineMode (because the serverless option is only for v1), the port number must be specified for the PostgreSQL engine; otherwise, it will use the default of 3306.
ServerlessV2ScalingConfiguration: To define our scaling configuration there are two properties:
DB Instance
The final building block for our cluster is the DB instance:
DBInstance:
Type: AWS::RDS::DBInstance
Properties:
DBClusterIdentifier: !Ref DBCluster
DBInstanceIdentifier: my-dbinstance
DBInstanceClass: db.serverless
Engine: aurora-postgresql
The properties defined in the instance are:
DBClusterIdentifier: The identifier of the DB cluster to which the instance will belong.
DBInstanceIdentifier: A name for the DB instance.
DBInstanceClass: The compute and memory capacity of the DB instance. In our case, we will use the special class type db.serverless.
Engine: The name of the database engine we want to use for this DB instance. In our case, we must use the same value specified in the cluster.
Deploy
To create all the resources, run:
sam build
sam deploy --guided
Once completed, run the following command to get our cluster's endpoints:
aws docdb describe-db-clusters --region us-east-2 --db-cluster-identifier my-dbcluster --query 'DBClusters[*].[DBClusterIdentifier,Port,Endpoint,ReaderEndpoint]'
Download a PostgreSQL client like PgAdmin and test the connection against the database.
Clean Up
Run the following command to delete all the resources:
sam delete
The final script can be found here. Thanks, and happy coding.
