feat(docdb): high level constrcuts for db clusters and instances (#6511)

- CDK users who want to want to use Amazon DocumentDB previously had to use the low-level auto-generated constructs (CFN Resources)
- Adds higher-level constructs for
- `AWS::DocDB::DBCluster`
- `AWS::DocDB::DBInstance`
- `AWS::DocDB::DBClusterParameterGroup`

fixes #6511

packages/@aws-cdk/aws-docdb/README.md

@@ -6,11 +6,81 @@
 
 > All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
 
+![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
+
+> The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
+
 ---
 <!--END STABILITY BANNER-->
 
-This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
+### 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:
+
+```ts
+const cluster = new DatabaseCluster(this, 'Database', {
+    masterUser: {
+        username: 'admin'
+    },
+    instanceProps: {
+        instanceType: ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
+        vpcSubnets: {
+            subnetType: ec2.SubnetType.PUBLIC,
+        },
+        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:
+
+```ts
+cluster.connections.allowDefaultPortFromAnyIpv4('Open to the world');
+```
+
+The endpoints to access your database cluster will be available as the `.clusterEndpoint` and `.clusterReadEndpoint`
+attributes:
 
 ```ts
-import * as docdb from '@aws-cdk/aws-docdb';
+const writeAddress = cluster.clusterEndpoint.socketAddress;   // "HOSTNAME:PORT"
 ```
+
+### Rotating credentials
+When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
+```ts
+cluster.addRotationSingleUser(); // Will rotate automatically after 30 days
+```
+
+[example of setting up master password rotation for a cluster](test/integ.cluster-rotation.lit.ts)
+
+The multi user rotation scheme is also available:
+```ts
+cluster.addRotationMultiUser('MyUser', {
+  secret: myImportedSecret // This secret must have the `masterarn` key
+});
+```
+
+It's also possible to create user credentials together with the cluster and add rotation:
+```ts
+const myUserSecret = new docdb.DatabaseSecret(this, 'MyUserSecret', {
+  username: 'myuser',
+  masterSecret: cluster.secret
+});
+const myUserSecretAttached = myUserSecret.attach(cluster); // Adds DB connections information in the secret
+
+cluster.addRotationMultiUser('MyUser', { // Add rotation using the multi user scheme
+  secret: myUserSecretAttached // This secret must have the `masterarn` key
+});
+```
+**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](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-secretsmanager/README.md) for credentials rotation of existing clusters.

packages/@aws-cdk/aws-docdb/lib/cluster-ref.ts

@@ -0,0 +1,82 @@
+import { IConnectable, ISecurityGroup } from '@aws-cdk/aws-ec2';
+import { ISecretAttachmentTarget } from '@aws-cdk/aws-secretsmanager';
+import { IResource } from '@aws-cdk/core';
+import { Endpoint } from './endpoint';
+
+/**
+ * Create a clustered database with a given number of instances.
+ */
+export interface IDatabaseCluster extends IResource, IConnectable, ISecretAttachmentTarget {
+  /**
+   * Identifier of the cluster
+   */
+  readonly clusterIdentifier: string;
+
+  /**
+   * Identifiers of the replicas
+   */
+  readonly instanceIdentifiers: string[];
+
+  /**
+   * The endpoint to use for read/write operations
+   * @attribute Endpoint,Port
+   */
+  readonly clusterEndpoint: Endpoint;
+
+  /**
+   * Endpoint to use for load-balanced read-only operations.
+   * @attribute ReadEndpoint
+   */
+  readonly clusterReadEndpoint: Endpoint;
+
+  /**
+   * Endpoints which address each individual replica.
+   */
+  readonly instanceEndpoints: Endpoint[];
+
+  /**
+   * The security group for this database cluster
+   */
+  readonly securityGroupId: string;
+}
+
+/**
+ * Properties that describe an existing cluster instance
+ */
+export interface DatabaseClusterAttributes {
+  /**
+   * The database port
+   */
+  readonly port: number;
+
+  /**
+   * The security group of the database cluster
+   */
+  readonly securityGroup: ISecurityGroup;
+
+  /**
+   * Identifier for the cluster
+   */
+  readonly clusterIdentifier: string;
+
+  /**
+   * Identifier for the instances
+   */
+  readonly instanceIdentifiers: string[];
+  // Actual underlying type: DBInstanceId[], but we have to type it more loosely for Java's benefit.
+
+  /**
+   * Cluster endpoint address
+   */
+  readonly clusterEndpointAddress: string;
+
+  /**
+   * Reader endpoint address
+   */
+  readonly readerEndpointAddress: string;
+
+  /**
+   * Endpoint addresses of individual instances
+   */
+  readonly instanceEndpointAddresses: string[];
+}