agent-claw: automated task changes
This commit is contained in:
daniel
304
cdk/node_modules/aws-cdk-lib/aws-docdb/README.md
generated
vendored
Normal file
304
cdk/node_modules/aws-cdk-lib/aws-docdb/README.md
generated
vendored
Normal file
@@ -0,0 +1,304 @@
|
||||
# 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:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
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', // optional, if you prefer to specify the secret name
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
copyTagsToSnapshot: true // whether to save the cluster tags when creating the snapshot.
|
||||
});
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Serverless Clusters
|
||||
|
||||
DocumentDB supports serverless clusters that automatically scale capacity based on your application's needs.
|
||||
To create a serverless cluster, specify the `serverlessV2ScalingConfiguration` instead of `instanceType`:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
vpc,
|
||||
serverlessV2ScalingConfiguration: {
|
||||
minCapacity: 0.5,
|
||||
maxCapacity: 2,
|
||||
},
|
||||
engineVersion: '5.0.0', // Serverless requires engine version 5.0.0 or higher
|
||||
});
|
||||
```
|
||||
|
||||
**Note**: DocumentDB serverless requires engine version 5.0.0 or higher and is not compatible with all features. See the [AWS documentation](https://docs.aws.amazon.com/documentdb/latest/developerguide/docdb-serverless-limitations.html) for limitations.
|
||||
|
||||
## 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
|
||||
declare const cluster: docdb.DatabaseCluster;
|
||||
cluster.connections.allowDefaultPortFromAnyIpv4('Open to the world');
|
||||
```
|
||||
|
||||
The endpoints to access your database cluster will be available as the `.clusterEndpoint` and `.clusterReadEndpoint`
|
||||
attributes:
|
||||
|
||||
```ts
|
||||
declare const cluster: docdb.DatabaseCluster;
|
||||
const writeAddress = cluster.clusterEndpoint.socketAddress; // "HOSTNAME:PORT"
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
declare const cluster: docdb.DatabaseCluster;
|
||||
|
||||
const securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', {
|
||||
vpc,
|
||||
});
|
||||
cluster.addSecurityGroups(securityGroup);
|
||||
```
|
||||
|
||||
## Deletion protection
|
||||
|
||||
Deletion protection can be enabled on an Amazon DocumentDB cluster to prevent accidental deletion of the cluster:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
deletionProtection: true, // Enable deletion protection.
|
||||
});
|
||||
```
|
||||
|
||||
## Rotating credentials
|
||||
|
||||
When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
|
||||
|
||||
```ts
|
||||
declare const cluster: docdb.DatabaseCluster;
|
||||
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
|
||||
import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
|
||||
|
||||
declare const myImportedSecret: secretsmanager.Secret;
|
||||
declare const cluster: docdb.DatabaseCluster;
|
||||
|
||||
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
|
||||
declare const cluster: docdb.DatabaseCluster;
|
||||
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-lib/aws-secretsmanager](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-secretsmanager/README.md) for credentials rotation of existing clusters.
|
||||
|
||||
## Audit and profiler Logs
|
||||
|
||||
Sending audit or profiler needs to be configured in two places:
|
||||
|
||||
1. Check / create the needed options in your ParameterGroup for [audit](https://docs.aws.amazon.com/documentdb/latest/developerguide/event-auditing.html#event-auditing-enabling-auditing) and
|
||||
[profiler](https://docs.aws.amazon.com/documentdb/latest/developerguide/profiling.html#profiling.enable-profiling) logs.
|
||||
2. Enable the corresponding option(s) when creating the `DatabaseCluster`:
|
||||
|
||||
```ts
|
||||
import * as iam from 'aws-cdk-lib/aws-iam';
|
||||
import * as logs from'aws-cdk-lib/aws-logs';
|
||||
|
||||
declare const myLogsPublishingRole: iam.Role;
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
exportProfilerLogsToCloudWatch: true, // Enable sending profiler logs
|
||||
exportAuditLogsToCloudWatch: true, // Enable sending audit logs
|
||||
cloudWatchLogsRetention: logs.RetentionDays.THREE_MONTHS, // Optional - default is to never expire logs
|
||||
cloudWatchLogsRetentionRole: myLogsPublishingRole, // Optional - a role will be created if not provided
|
||||
});
|
||||
```
|
||||
|
||||
## Enable Performance Insights
|
||||
|
||||
By enabling this feature it will be cascaded and enabled in all instances inside the cluster:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
enablePerformanceInsights: true, // Enable Performance Insights in all instances under this cluster
|
||||
});
|
||||
```
|
||||
|
||||
## Removal Policy
|
||||
|
||||
This resource supports the snapshot removal policy.
|
||||
To specify it use the `removalPolicy` property:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
removalPolicy: RemovalPolicy.SNAPSHOT,
|
||||
});
|
||||
```
|
||||
|
||||
**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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html) for more details.
|
||||
|
||||
To specify a custom removal policy for the cluster's instances, use the
|
||||
`instanceRemovalPolicy` property:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
removalPolicy: RemovalPolicy.SNAPSHOT,
|
||||
instanceRemovalPolicy: RemovalPolicy.RETAIN,
|
||||
});
|
||||
```
|
||||
|
||||
To specify a custom removal policy for the cluster's security group, use the
|
||||
`securityGroupRemovalPolicy` property:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
removalPolicy: RemovalPolicy.SNAPSHOT,
|
||||
securityGroupRemovalPolicy: RemovalPolicy.RETAIN,
|
||||
});
|
||||
```
|
||||
|
||||
## CA certificate
|
||||
|
||||
Use the `caCertificate` property to specify the [CA certificate](https://docs.aws.amazon.com/documentdb/latest/developerguide/ca_cert_rotation.html) to use for all instances inside the cluster:
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpcSubnets: {
|
||||
subnetType: ec2.SubnetType.PUBLIC,
|
||||
},
|
||||
vpc,
|
||||
caCertificate: docdb.CaCertificate.RDS_CA_RSA4096_G1, // CA certificate for all instances under this cluster
|
||||
});
|
||||
```
|
||||
|
||||
## Storage Type
|
||||
|
||||
You can specify [storage type](https://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-storage-configs.html) for the cluster.
|
||||
|
||||
```ts
|
||||
declare const vpc: ec2.Vpc;
|
||||
|
||||
const cluster = new docdb.DatabaseCluster(this, 'Database', {
|
||||
masterUser: {
|
||||
username: 'myuser',
|
||||
},
|
||||
instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
|
||||
vpc,
|
||||
storageType: docdb.StorageType.IOPT1, // Default is StorageType.STANDARD
|
||||
});
|
||||
```
|
||||
|
||||
**Note**: `StorageType.IOPT1` is supported starting with engine version 5.0.0.
|
||||
|
||||
**Note**: For serverless clusters, storage type is managed automatically and cannot be specified.
|
||||
Reference in New Issue
Block a user