CDK Constructs for AWS RDS
Project description
Amazon Relational Database Service Construct Library
---This is a developer preview (public beta) module. Releases might lack important features and might have future breaking changes.
This API is still under active development and subject to non-backward compatible changes or removal in any future version. Use of the API is not recommended in production environments. Experimental APIs are not subject to the Semantic Versioning model.
Starting a Clustered Database
To set up a clustered database (like Aurora), define a DatabaseCluster
. You must
always launch a database in a VPC. Use the vpcSubnets
attribute to control whether
your instances will be launched privately or publicly:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
cluster = DatabaseCluster(self, "Database",
engine=DatabaseClusterEngine.AURORA,
master_user={
"username": "admin"
},
instance_props={
"instance_type": ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.SMALL),
"vpc_subnets": {
"subnet_type": ec2.SubnetType.PUBLIC
},
"vpc": vpc
}
)
By default, the master password will be generated and stored in AWS Secrets Manager.
Your cluster will be empty by default. To add a default database upon construction, specify the
defaultDatabaseName
attribute.
Starting an Instance Database
To set up a instance database, define a DatabaseInstance
. You must
always launch a database in a VPC. Use the vpcSubnets
attribute to control whether
your instances will be launched privately or publicly:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
instance = DatabaseInstance(stack, "Instance",
engine=rds.DatabaseInstanceEngine.ORACLE_SE1,
instance_class=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.SMALL),
master_username="syscdk",
vpc=vpc
)
By default, the master password will be generated and stored in AWS Secrets Manager.
Use DatabaseInstanceFromSnapshot
and DatabaseInstanceReadReplica
to create an instance from snapshot or
a source database respectively:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
DatabaseInstanceFromSnapshot(stack, "Instance",
snapshot_identifier="my-snapshot",
engine=rds.DatabaseInstanceEngine.POSTGRES,
instance_class=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.LARGE),
vpc=vpc
)
DatabaseInstanceReadReplica(stack, "ReadReplica",
source_database_instance=source_instance,
engine=rds.DatabaseInstanceEngine.POSTGRES,
instance_class=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.LARGE),
vpc=vpc
)
Creating a "production" Oracle database instance with option and parameter groups:
# Example automatically generated. See https://github.com/aws/jsii/issues/826
# Set open cursors with parameter group
parameter_group = rds.ParameterGroup(self, "ParameterGroup",
family="oracle-se1-11.2",
parameters={
"open_cursors": "2500"
}
)
option_group = rds.OptionGroup(self, "OptionGroup",
engine=rds.DatabaseInstanceEngine.ORACLE_SE1,
major_engine_version="11.2",
configurations=[OptionConfiguration(
name="XMLDB"
), OptionConfiguration(
name="OEM",
port=1158,
vpc=vpc
)
]
)
# Allow connections to OEM
option_group.option_connections.OEM.connections.allow_default_port_from_any_ipv4()
# Database instance with production values
instance = rds.DatabaseInstance(self, "Instance",
engine=rds.DatabaseInstanceEngine.ORACLE_SE1,
license_model=rds.LicenseModel.BRING_YOUR_OWN_LICENSE,
instance_class=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.MEDIUM),
multi_az=True,
storage_type=rds.StorageType.IO1,
master_username="syscdk",
vpc=vpc,
database_name="ORCL",
storage_encrypted=True,
backup_retention=cdk.Duration.days(7),
monitoring_interval=cdk.Duration.seconds(60),
enable_performance_insights=True,
cloudwatch_logs_exports=["trace", "audit", "alert", "listener"
],
cloudwatch_logs_retention=logs.RetentionDays.ONE_MONTH,
auto_minor_version_upgrade=False,
option_group=option_group,
parameter_group=parameter_group
)
# Allow connections on default port from any IPV4
instance.connections.allow_default_port_from_any_ipv4()
# Rotate the master user password every 30 days
instance.add_rotation_single_user()
# Add alarm for high CPU
cloudwatch.Alarm(self, "HighCPU",
metric=instance.metric_cPUUtilization(),
threshold=90,
evaluation_periods=1
)
# Trigger Lambda function on instance availability events
fn = lambda.Function(self, "Function",
code=lambda.Code.from_inline("exports.handler = (event) => console.log(event);"),
handler="index.handler",
runtime=lambda.Runtime.NODEJS_10_X
)
availability_rule = instance.on_event("Availability", target=targets.LambdaFunction(fn))
availability_rule.add_event_pattern(
detail={
"EventCategories": ["availability"
]
}
)
Add XMLDB and OEM with option group
# Example automatically generated. See https://github.com/aws/jsii/issues/826
# Set open cursors with parameter group
parameter_group = rds.ParameterGroup(self, "ParameterGroup",
family="oracle-se1-11.2",
parameters={
"open_cursors": "2500"
}
)
option_group = rds.OptionGroup(self, "OptionGroup",
engine=rds.DatabaseInstanceEngine.ORACLE_SE1,
major_engine_version="11.2",
configurations=[OptionConfiguration(
name="XMLDB"
), OptionConfiguration(
name="OEM",
port=1158,
vpc=vpc
)
]
)
# Allow connections to OEM
option_group.option_connections.OEM.connections.allow_default_port_from_any_ipv4()
# Database instance with production values
instance = rds.DatabaseInstance(self, "Instance",
engine=rds.DatabaseInstanceEngine.ORACLE_SE1,
license_model=rds.LicenseModel.BRING_YOUR_OWN_LICENSE,
instance_class=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.MEDIUM),
multi_az=True,
storage_type=rds.StorageType.IO1,
master_username="syscdk",
vpc=vpc,
database_name="ORCL",
storage_encrypted=True,
backup_retention=cdk.Duration.days(7),
monitoring_interval=cdk.Duration.seconds(60),
enable_performance_insights=True,
cloudwatch_logs_exports=["trace", "audit", "alert", "listener"
],
cloudwatch_logs_retention=logs.RetentionDays.ONE_MONTH,
auto_minor_version_upgrade=False,
option_group=option_group,
parameter_group=parameter_group
)
# Allow connections on default port from any IPV4
instance.connections.allow_default_port_from_any_ipv4()
# Rotate the master user password every 30 days
instance.add_rotation_single_user()
# Add alarm for high CPU
cloudwatch.Alarm(self, "HighCPU",
metric=instance.metric_cPUUtilization(),
threshold=90,
evaluation_periods=1
)
# Trigger Lambda function on instance availability events
fn = lambda.Function(self, "Function",
code=lambda.Code.from_inline("exports.handler = (event) => console.log(event);"),
handler="index.handler",
runtime=lambda.Runtime.NODEJS_10_X
)
availability_rule = instance.on_event("Availability", target=targets.LambdaFunction(fn))
availability_rule.add_event_pattern(
detail={
"EventCategories": ["availability"
]
}
)
Instance events
To define Amazon CloudWatch event rules for database instances, use the onEvent
method:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
rule = instance.on_event("InstanceEvent", target=targets.LambdaFunction(fn))
Connecting
To control who can access the cluster or instance, use the .connections
attribute. RDS databases have
a default port, so you don't need to specify the port:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
cluster.connections.allow_from_any_ipv4("Open to the world")
The endpoints to access your database cluster will be available as the .clusterEndpoint
and .readerEndpoint
attributes:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
write_address = cluster.cluster_endpoint.socket_address
For an instance database:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
address = instance.instance_endpoint.socket_address
Rotating credentials
When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
instance.add_rotation_single_user()
# Example automatically generated. See https://github.com/aws/jsii/issues/826
cluster = rds.DatabaseCluster(stack, "Database",
engine=rds.DatabaseClusterEngine.AURORA,
master_user=Login(
username="admin"
),
instance_props={
"instance_type": ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL),
"vpc": vpc
}
)
cluster.add_rotation_single_user()
The multi user rotation scheme is also available:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
instance.add_rotation_multi_user("MyUser",
secret=my_imported_secret
)
It's also possible to create user credentials together with the instance/cluster and add rotation:
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
my_user_secret = rds.DatabaseSecret(self, "MyUserSecret",
username="myuser"
)
my_user_secret_attached = my_user_secret.attach(instance)# Adds DB connections information in the secret
instance.add_rotation_multi_user("MyUser", # Add rotation using the multi user scheme
secret=my_user_secret_attached)
Note: This user must be created manually in the database using the master credentials. The rotation will start as soon as this user exists.
See also @aws-cdk/aws-secretsmanager for credentials rotation of existing clusters/instances.
Metrics
Database instances expose metrics (cloudwatch.Metric
):
# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
# The number of database connections in use (average over 5 minutes)
db_connections = instance.metric_database_connections()
# The average amount of time taken per disk I/O operation (average over 1 minute)
read_latency = instance.metric("ReadLatency", statistic="Average", period_sec=60)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aws_cdk.aws_rds-1.21.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 699e5f9c8f7949529b1a7564ae4dd18b0701e6260466755e9226a3ddd5f11572 |
|
MD5 | 9453cce46087caae0370f8f8b938cc3d |
|
BLAKE2b-256 | e7784b1bf27872fae0a0026541f3104c7b77825775f68c0d91dd12906e12227f |