Package software.amazon.awscdk.services.docdb
Amazon DocumentDB Construct Library
Starting a Clustered Database
To set up a clustered DocumentDB database, 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:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") // NOTE: 'admin' is reserved by DocumentDB .excludeCharacters("\"@/:") // optional, defaults to the set "\"@/" and is also used for eventually created rotations .secretName("/myapp/mydocdb/masteruser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .copyTagsToSnapshot(true) .build();
By default, the master password will be generated and stored in AWS Secrets Manager with auto-generated description.
Your cluster will be empty by default.
Connecting
To control who can access the cluster, use the .connections
attribute. DocumentDB databases have a default port, so
you don't need to specify the port:
DatabaseCluster cluster; cluster.connections.allowDefaultPortFromAnyIpv4("Open to the world");
The endpoints to access your database cluster will be available as the .clusterEndpoint
and .clusterReadEndpoint
attributes:
DatabaseCluster cluster; String writeAddress = cluster.getClusterEndpoint().getSocketAddress();
If you have existing security groups you would like to add to the cluster, use the addSecurityGroups
method. Security
groups added in this way will not be managed by the Connections
object of the cluster.
Vpc vpc; DatabaseCluster cluster; SecurityGroup securityGroup = SecurityGroup.Builder.create(this, "SecurityGroup") .vpc(vpc) .build(); cluster.addSecurityGroups(securityGroup);
Deletion protection
Deletion protection can be enabled on an Amazon DocumentDB cluster to prevent accidental deletion of the cluster:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .deletionProtection(true) .build();
Rotating credentials
When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
DatabaseCluster cluster; cluster.addRotationSingleUser();
DatabaseCluster cluster = DatabaseCluster.Builder.create(stack, "Database") .masterUser(Login.builder() .username("docdb") .build()) .instanceType(InstanceType.of(InstanceClass.R5, InstanceSize.LARGE)) .vpc(vpc) .removalPolicy(RemovalPolicy.DESTROY) .build(); cluster.addRotationSingleUser();
The multi user rotation scheme is also available:
import software.amazon.awscdk.services.secretsmanager.*; Secret myImportedSecret; DatabaseCluster cluster; cluster.addRotationMultiUser("MyUser", RotationMultiUserOptions.builder() .secret(myImportedSecret) .build());
It's also possible to create user credentials together with the cluster and add rotation:
DatabaseCluster cluster; DatabaseSecret myUserSecret = DatabaseSecret.Builder.create(this, "MyUserSecret") .username("myuser") .masterSecret(cluster.getSecret()) .build(); ISecret myUserSecretAttached = myUserSecret.attach(cluster); // Adds DB connections information in the secret cluster.addRotationMultiUser("MyUser", RotationMultiUserOptions.builder() // Add rotation using the multi user scheme .secret(myUserSecretAttached).build());
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-lib/aws-secretsmanager for credentials rotation of existing clusters.
Audit and profiler Logs
Sending audit or profiler needs to be configured in two places:
- Check / create the needed options in your ParameterGroup for audit and profiler logs.
- Enable the corresponding option(s) when creating the
DatabaseCluster
:
import software.amazon.awscdk.services.iam.*; import software.amazon.awscdk.services.logs.*; Role myLogsPublishingRole; Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .exportProfilerLogsToCloudWatch(true) // Enable sending profiler logs .exportAuditLogsToCloudWatch(true) // Enable sending audit logs .cloudWatchLogsRetention(RetentionDays.THREE_MONTHS) // Optional - default is to never expire logs .cloudWatchLogsRetentionRole(myLogsPublishingRole) .build();
Enable Performance Insights
By enabling this feature it will be cascaded and enabled in all instances inside the cluster:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .enablePerformanceInsights(true) .build();
## Removal Policy
This resource supports the snapshot removal policy.
To specify it use the removalPolicy
property:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .removalPolicy(RemovalPolicy.SNAPSHOT) .build();
Note: A RemovalPolicy.DESTROY
removal policy will be applied to the
cluster's instances and security group by default as they don't support the snapshot
removal policy.
Visit DeletionPolicy for more details.
To specify a custom removal policy for the cluster's instances, use the
instanceRemovalPolicy
property:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .removalPolicy(RemovalPolicy.SNAPSHOT) .instanceRemovalPolicy(RemovalPolicy.RETAIN) .build();
To specify a custom removal policy for the cluster's security group, use the
securityGroupRemovalPolicy
property:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .removalPolicy(RemovalPolicy.SNAPSHOT) .securityGroupRemovalPolicy(RemovalPolicy.RETAIN) .build();
CA certificate
Use the caCertificate
property to specify the CA certificate to use for all instances inside the cluster:
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpcSubnets(SubnetSelection.builder() .subnetType(SubnetType.PUBLIC) .build()) .vpc(vpc) .caCertificate(CaCertificate.RDS_CA_RSA4096_G1) .build();
Storage Type
You can specify storage type for the cluster.
Vpc vpc; DatabaseCluster cluster = DatabaseCluster.Builder.create(this, "Database") .masterUser(Login.builder() .username("myuser") .build()) .instanceType(InstanceType.of(InstanceClass.MEMORY5, InstanceSize.LARGE)) .vpc(vpc) .storageType(StorageType.IOPT1) .build();
Note: StorageType.IOPT1
is supported starting with engine version 5.0.0.
-
ClassDescriptionBackup configuration for DocumentDB databases.A builder for
BackupProps
An implementation forBackupProps
The CA certificate used for a DB instance.TheAWS::DocDB::DBCluster
Amazon DocumentDB (with MongoDB compatibility) resource describes a DBCluster.A fluent builder forCfnDBCluster
.TheAWS::DocDB::DBClusterParameterGroup
Amazon DocumentDB (with MongoDB compatibility) resource describes a DBClusterParameterGroup.A fluent builder forCfnDBClusterParameterGroup
.Properties for defining aCfnDBClusterParameterGroup
.A builder forCfnDBClusterParameterGroupProps
An implementation forCfnDBClusterParameterGroupProps
Properties for defining aCfnDBCluster
.A builder forCfnDBClusterProps
An implementation forCfnDBClusterProps
TheAWS::DocDB::DBInstance
Amazon DocumentDB (with MongoDB compatibility) resource describes a DBInstance.A fluent builder forCfnDBInstance
.Properties for defining aCfnDBInstance
.A builder forCfnDBInstanceProps
An implementation forCfnDBInstanceProps
TheAWS::DocDB::DBSubnetGroup
Amazon DocumentDB (with MongoDB compatibility) resource describes a DBSubnetGroup.A fluent builder forCfnDBSubnetGroup
.Properties for defining aCfnDBSubnetGroup
.A builder forCfnDBSubnetGroupProps
An implementation forCfnDBSubnetGroupProps
Creates an Amazon DocumentDB event notification subscription.A fluent builder forCfnEventSubscription
.Properties for defining aCfnEventSubscription
.A builder forCfnEventSubscriptionProps
An implementation forCfnEventSubscriptionProps
A cluster parameter group.A fluent builder forClusterParameterGroup
.Properties for a cluster parameter group.A builder forClusterParameterGroupProps
An implementation forClusterParameterGroupProps
Create a clustered database with a given number of instances.A fluent builder forDatabaseCluster
.Properties that describe an existing cluster instance.A builder forDatabaseClusterAttributes
An implementation forDatabaseClusterAttributes
Properties for a new database cluster.A builder forDatabaseClusterProps
An implementation forDatabaseClusterProps
A database instance.A fluent builder forDatabaseInstance
.Properties that describe an existing instance.A builder forDatabaseInstanceAttributes
An implementation forDatabaseInstanceAttributes
Construction properties for a DatabaseInstanceNew.A builder forDatabaseInstanceProps
An implementation forDatabaseInstanceProps
A database secret.A fluent builder forDatabaseSecret
.Construction properties for a DatabaseSecret.A builder forDatabaseSecretProps
An implementation forDatabaseSecretProps
Connection endpoint of a database cluster or instance.A parameter group.Internal default implementation forIClusterParameterGroup
.A proxy class which represents a concrete javascript instance of this type.Create a clustered database with a given number of instances.Internal default implementation forIDatabaseCluster
.A proxy class which represents a concrete javascript instance of this type.A database instance.Internal default implementation forIDatabaseInstance
.A proxy class which represents a concrete javascript instance of this type.Login credentials for a database cluster.A builder forLogin
An implementation forLogin
Options to add the multi user rotation.A builder forRotationMultiUserOptions
An implementation forRotationMultiUserOptions
The storage type of the DocDB cluster.