@smallcase/cdk-rds-module

v0.0.7

Published

4 months ago

A comprehensive AWS CDK construct for provisioning PostgreSQL RDS instances with advanced monitoring, alerting, and Zenduty integration.

0High
0Medium
0Low

AWS CDK RDS Module

A comprehensive AWS CDK construct for provisioning PostgreSQL RDS instances with advanced monitoring, alerting, and Zenduty integration.

🚀 Features

PostgreSQL RDS Clusters: Primary instances with optional read replicas
Advanced Monitoring: Comprehensive CloudWatch alarms for performance metrics
Dynamic Thresholds: Alert thresholds that automatically adjust based on instance type
Custom Thresholds: Override default thresholds for primary and replica instances
Zenduty Integration: Direct webhook integration for incident management
Cost Control: Optional alert disabling for non-production environments
Flexible Configuration: Support for multiple webhook endpoints
Tagging Support: Automatic tag propagation to all resources

📦 Installation

npm install @your-org/cdk-rds-module
# or
yarn add @your-org/cdk-rds-module

🏗️ Basic Usage

import * as cdk from 'aws-cdk-lib';
import { PostgresRDSCluster } from '@your-org/cdk-rds-module';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyRDSStack');

new PostgresRDSCluster(stack, 'MyDatabase', {
  clusterName: 'my-app-db',
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MICRO),
  vpc: myVpc,
  postgresVersion: rds.DatabaseInstanceEngine.postgres({ version: rds.PostgresEngineVersion.VER_14_7 }),
  databaseName: 'myapp',
  masterUsername: 'admin',
  masterUserPassword: cdk.SecretValue.unsafePlainText('password123'),
  backupRetention: 7,
  multiAz: false,
  enablePerformanceInsights: true,
  performanceInsightRetention: 7,
  monitoringInterval: 60,
  deletionProtection: false,
  storageEncrypted: true,
  enableAlerts: true,
  alertSubcriptionWebhooks: ['https://your-zenduty-webhook-url'],
  metricTopicName: 'my-app-alerts',
});

🔧 Configuration Options

Core RDS Configuration

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | clusterName | string | ✅ | - | Unique name for the RDS cluster | | instanceType | ec2.InstanceType | ✅ | - | EC2 instance type for the database | | vpc | ec2.IVpc | ✅ | - | VPC where the RDS instance will be deployed | | postgresVersion | rds.IInstanceEngine | ✅ | - | PostgreSQL engine version | | databaseName | string | ✅ | - | Name of the database to create | | masterUsername | string | ✅ | - | Master username for the database | | masterUserPassword | cdk.SecretValue | ✅ | - | Master password for the database |

Read Replicas

readReplicas: {
  replicas: 2,
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.SMALL),
  parameters: {
    'shared_preload_libraries': 'pg_stat_statements',
    'max_connections': '200'
  },
  alertThresholds: {
    cpu: 70,
    memory: 1073741824, // 1GB in bytes
    freeStorage: 2147483648, // 2GB in bytes
    readIops: 1000,
    writeIops: 500,
    diskQueueDepth: 10,
    dbConnections: 80,
    networkThroughput: 10485760, // 10MB/s in bytes
    replicationLag: 5000 // 5 seconds in milliseconds
  }
}

Monitoring & Alerting

| Property | Type | Default | Description | |----------|------|---------|-------------| | enableAlerts | boolean | true | Enable/disable all CloudWatch alarms | | alertSubcriptionWebhooks | string[] | [] | Array of webhook URLs for notifications | | metricTopicName | string | clusterName | SNS topic name for alerts | | primaryAlertThresholds | AlertThresholds | Dynamic | Custom thresholds for primary instance | | replicaAlertThresholds | AlertThresholds | Dynamic | Custom thresholds for read replicas |

Alert Thresholds Interface

interface AlertThresholds {
  readonly cpu: number;                    // CPU utilization percentage
  readonly memory: number;                 // Free memory in bytes
  readonly freeStorage: number;            // Free storage in bytes
  readonly readIops: number;               // Read IOPS threshold
  readonly writeIops: number;              // Write IOPS threshold
  readonly diskQueueDepth: number;         // Disk queue depth
  readonly dbConnections: number;          // Database connections percentage
  readonly networkThroughput: number;      // Network throughput in bytes
  readonly replicationLag: number;         // Replication lag in milliseconds
}

📊 Dynamic Thresholds

The module automatically calculates appropriate alert thresholds based on the RDS instance type:

Instance Type Thresholds

| Instance Class | CPU (%) | Memory (GB) | Storage (GB) | Read IOPS | Write IOPS | |----------------|---------|-------------|--------------|-----------|------------| | t3.micro | 80 | 0.5 | 5 | 1000 | 500 | | t3.small | 80 | 1 | 10 | 2000 | 1000 | | t3.medium | 80 | 2 | 20 | 3000 | 1500 | | m6.large | 80 | 4 | 50 | 5000 | 2500 | | m6.xlarge | 80 | 8 | 100 | 10000 | 5000 | | r6.large | 80 | 16 | 100 | 8000 | 4000 | | r6.xlarge | 80 | 32 | 200 | 15000 | 7500 |

🔔 Available Alerts

Primary Instance Alerts

CPU Utilization: Monitors CPU usage percentage
Free Storage Space: Alerts when storage is running low
Free Memory: Monitors available memory
Read IOPS: Tracks read operations per second
Write IOPS: Tracks write operations per second
Disk Queue Depth: Monitors I/O queue length
Database Connections: Tracks active connections
Network Throughput: Monitors network bandwidth
Backup Storage: Tracks backup storage usage

Read Replica Alerts

All primary alerts plus:
Replication Lag: Monitors replication delay

🔗 Zenduty Integration

Setup Zenduty Webhook

Create a new integration in Zenduty
Select "AWS CloudWatch" as the integration type
Copy the webhook URL
Add it to your CDK configuration:

alertSubcriptionWebhooks: [
  'https://your-zenduty-webhook-url'
]

Multiple Webhooks

Support multiple notification endpoints:

alertSubcriptionWebhooks: [
  'https://zenduty-webhook-url',
  'https://slack-webhook-url',
  'https://pagerduty-webhook-url'
]

🏷️ Tagging

All resources are automatically tagged with:

Name: Resource name
Environment: Stack environment
Project: Project identifier
Custom tags passed via the tags property

💰 Cost Optimization

Disable Alerts for Non-Production

new PostgresRDSCluster(stack, 'DevDatabase', {
  // ... other config
  enableAlerts: false, // Disable all alerts for cost savings
});

Conditional Alert Configuration

const isProduction = process.env.ENVIRONMENT === 'production';

new PostgresRDSCluster(stack, 'MyDatabase', {
  // ... other config
  enableAlerts: isProduction,
  alertSubcriptionWebhooks: isProduction ? ['https://prod-zenduty-webhook'] : [],
});

📋 Examples

Basic RDS Instance

import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as rds from 'aws-cdk-lib/aws-rds';
import { PostgresRDSCluster } from '@your-org/cdk-rds-module';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'BasicRDSStack');

const vpc = new ec2.Vpc(stack, 'MyVPC');

new PostgresRDSCluster(stack, 'BasicDatabase', {
  clusterName: 'basic-app-db',
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MICRO),
  vpc: vpc,
  postgresVersion: rds.DatabaseInstanceEngine.postgres({ version: rds.PostgresEngineVersion.VER_14_7 }),
  databaseName: 'myapp',
  masterUsername: 'admin',
  masterUserPassword: cdk.SecretValue.unsafePlainText('password123'),
  backupRetention: 7,
  multiAz: false,
  enablePerformanceInsights: true,
  performanceInsightRetention: 7,
  monitoringInterval: 60,
  deletionProtection: false,
  storageEncrypted: true,
});

Production RDS with Read Replicas

import { AlertThresholds } from '@your-org/cdk-rds-module';

const customThresholds: AlertThresholds = {
  cpu: 75,
  memory: 2147483648, // 2GB
  freeStorage: 5368709120, // 5GB
  readIops: 2000,
  writeIops: 1000,
  diskQueueDepth: 5,
  dbConnections: 70,
  networkThroughput: 20971520, // 20MB/s
  replicationLag: 3000, // 3 seconds
};

new PostgresRDSCluster(stack, 'ProductionDatabase', {
  clusterName: 'prod-app-db',
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.M6, ec2.InstanceSize.LARGE),
  vpc: vpc,
  postgresVersion: rds.DatabaseInstanceEngine.postgres({ version: rds.PostgresEngineVersion.VER_14_7 }),
  databaseName: 'myapp',
  masterUsername: 'admin',
  masterUserPassword: cdk.SecretValue.unsafePlainText('secure-password'),
  backupRetention: 30,
  multiAz: true,
  enablePerformanceInsights: true,
  performanceInsightRetention: 30,
  monitoringInterval: 60,
  deletionProtection: true,
  storageEncrypted: true,
  readReplicas: {
    replicas: 2,
    instanceType: ec2.InstanceType.of(ec2.InstanceClass.M6, ec2.InstanceSize.LARGE),
    alertThresholds: customThresholds,
  },
  primaryAlertThresholds: customThresholds,
  alertSubcriptionWebhooks: ['https://prod-zenduty-webhook'],
  metricTopicName: 'prod-app-alerts',
});

🧪 Testing

# Run tests
npm test

# Build the project
npm run build

# Check for linting issues
npm run lint

📚 API Reference

PostgresRDSCluster

Main construct for creating PostgreSQL RDS clusters.

Properties

cluster: rds.DatabaseInstance - The primary RDS instance
readReplicas: rds.DatabaseInstanceReadReplica[] - Array of read replica instances
securityGroup: ec2.SecurityGroup - Security group for the RDS instances
metricSnsTopic: sns.ITopic - SNS topic for CloudWatch alarms

RDSMonitoring

Internal construct for managing monitoring and alerting.

Methods

createPrimaryMonitoring(instance): Creates alerts for primary instance
createReplicaMonitoring(instance, index): Creates alerts for read replica

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

Create an issue in the GitHub repository
Check the documentation
Review the examples directory