Namespace Amazon.CDK.AWS.DocDB
Amazon DocumentDB Construct Library
---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.
For more information on how to migrate, see the Migrating to AWS CDK v2 guide.
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;
var cluster = new DatabaseCluster(this, "Database", new DatabaseClusterProps {
MasterUser = new Login {
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"
},
InstanceType = InstanceType.Of(InstanceClass.R5, InstanceSize.LARGE),
VpcSubnets = new SubnetSelection {
SubnetType = SubnetType.PUBLIC
},
Vpc = vpc
});
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;
var writeAddress = cluster.ClusterEndpoint.SocketAddress;
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;
var securityGroup = new SecurityGroup(this, "SecurityGroup", new SecurityGroupProps {
Vpc = vpc
});
cluster.AddSecurityGroups(securityGroup);
Deletion protection
Deletion protection can be enabled on an Amazon DocumentDB cluster to prevent accidental deletion of the cluster:
Vpc vpc;
var cluster = new DatabaseCluster(this, "Database", new DatabaseClusterProps {
MasterUser = new Login {
Username = "myuser"
},
InstanceType = InstanceType.Of(InstanceClass.R5, InstanceSize.LARGE),
VpcSubnets = new SubnetSelection {
SubnetType = SubnetType.PUBLIC
},
Vpc = vpc,
DeletionProtection = true
});
Rotating credentials
When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
DatabaseCluster cluster;
cluster.AddRotationSingleUser();
var cluster = new DatabaseCluster(stack, "Database", new DatabaseClusterProps {
MasterUser = new Login {
Username = "docdb"
},
InstanceType = InstanceType.Of(InstanceClass.R5, InstanceSize.LARGE),
Vpc = vpc,
RemovalPolicy = RemovalPolicy.DESTROY
});
cluster.AddRotationSingleUser();
The multi user rotation scheme is also available:
using Amazon.CDK.AWS.SecretsManager;
Secret myImportedSecret;
DatabaseCluster cluster;
cluster.AddRotationMultiUser("MyUser", new RotationMultiUserOptions {
Secret = myImportedSecret
});
It's also possible to create user credentials together with the cluster and add rotation:
DatabaseCluster cluster;
var myUserSecret = new DatabaseSecret(this, "MyUserSecret", new DatabaseSecretProps {
Username = "myuser",
MasterSecret = cluster.Secret
});
var myUserSecretAttached = myUserSecret.Attach(cluster); // Adds DB connections information in the secret
cluster.AddRotationMultiUser("MyUser", new RotationMultiUserOptions { // Add rotation using the multi user scheme
Secret = myUserSecretAttached });
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.
Audit and profiler Logs
Sending audit or profiler needs to be configured in two places:
using Amazon.CDK.AWS.IAM;
using Amazon.CDK.AWS.Logs;
Role myLogsPublishingRole;
Vpc vpc;
var cluster = new DatabaseCluster(this, "Database", new DatabaseClusterProps {
MasterUser = new Login {
Username = "myuser"
},
InstanceType = InstanceType.Of(InstanceClass.R5, InstanceSize.LARGE),
VpcSubnets = new SubnetSelection {
SubnetType = SubnetType.PUBLIC
},
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
});
Classes
BackupProps | Backup configuration for DocumentDB databases. |
CfnDBCluster | A CloudFormation |
CfnDBClusterParameterGroup | A CloudFormation |
CfnDBClusterParameterGroupProps | Properties for defining a |
CfnDBClusterProps | Properties for defining a |
CfnDBInstance | A CloudFormation |
CfnDBInstanceProps | Properties for defining a |
CfnDBSubnetGroup | A CloudFormation |
CfnDBSubnetGroupProps | Properties for defining a |
ClusterParameterGroup | A cluster parameter group. |
ClusterParameterGroupProps | Properties for a cluster parameter group. |
DatabaseCluster | Create a clustered database with a given number of instances. |
DatabaseClusterAttributes | Properties that describe an existing cluster instance. |
DatabaseClusterProps | Properties for a new database cluster. |
DatabaseInstance | A database instance. |
DatabaseInstanceAttributes | Properties that describe an existing instance. |
DatabaseInstanceProps | Construction properties for a DatabaseInstanceNew. |
DatabaseSecret | A database secret. |
DatabaseSecretProps | Construction properties for a DatabaseSecret. |
Endpoint | Connection endpoint of a database cluster or instance. |
Login | Login credentials for a database cluster. |
RotationMultiUserOptions | Options to add the multi user rotation. |
Interfaces
IBackupProps | Backup configuration for DocumentDB databases. |
ICfnDBClusterParameterGroupProps | Properties for defining a |
ICfnDBClusterProps | Properties for defining a |
ICfnDBInstanceProps | Properties for defining a |
ICfnDBSubnetGroupProps | Properties for defining a |
IClusterParameterGroup | A parameter group. |
IClusterParameterGroupProps | Properties for a cluster parameter group. |
IDatabaseCluster | Create a clustered database with a given number of instances. |
IDatabaseClusterAttributes | Properties that describe an existing cluster instance. |
IDatabaseClusterProps | Properties for a new database cluster. |
IDatabaseInstance | A database instance. |
IDatabaseInstanceAttributes | Properties that describe an existing instance. |
IDatabaseInstanceProps | Construction properties for a DatabaseInstanceNew. |
IDatabaseSecretProps | Construction properties for a DatabaseSecret. |
ILogin | Login credentials for a database cluster. |
IRotationMultiUserOptions | Options to add the multi user rotation. |