# Amazon DocumentDB Construct Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
## 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:
```python
# vpc: ec2.Vpc
cluster = docdb.DatabaseCluster(self, "Database",
master_user=docdb.Login(
username="myuser", # NOTE: 'admin' is reserved by DocumentDB
exclude_characters="\"@/:", # optional, defaults to the set "\"@/" and is also used for eventually created rotations
secret_name="/myapp/mydocdb/masteruser"
),
instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
vpc_subnets=ec2.SubnetSelection(
subnet_type=ec2.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:
```python
# cluster: docdb.DatabaseCluster
cluster.connections.allow_default_port_from_any_ipv4("Open to the world")
```
The endpoints to access your database cluster will be available as the `.clusterEndpoint` and `.clusterReadEndpoint`
attributes:
```python
# cluster: docdb.DatabaseCluster
write_address = cluster.cluster_endpoint.socket_address
```
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.
```python
# vpc: ec2.Vpc
# cluster: docdb.DatabaseCluster
security_group = ec2.SecurityGroup(self, "SecurityGroup",
vpc=vpc
)
cluster.add_security_groups(security_group)
```
## Deletion protection
Deletion protection can be enabled on an Amazon DocumentDB cluster to prevent accidental deletion of the cluster:
```python
# vpc: ec2.Vpc
cluster = docdb.DatabaseCluster(self, "Database",
master_user=docdb.Login(
username="myuser"
),
instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
vpc_subnets=ec2.SubnetSelection(
subnet_type=ec2.SubnetType.PUBLIC
),
vpc=vpc,
deletion_protection=True
)
```
## Rotating credentials
When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
```python
# cluster: docdb.DatabaseCluster
cluster.add_rotation_single_user()
```
```python
cluster = docdb.DatabaseCluster(stack, "Database",
master_user=docdb.Login(
username="docdb"
),
instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
vpc=vpc,
removal_policy=cdk.RemovalPolicy.DESTROY
)
cluster.add_rotation_single_user()
```
The multi user rotation scheme is also available:
```python
import aws_cdk.aws_secretsmanager as secretsmanager
# my_imported_secret: secretsmanager.Secret
# cluster: docdb.DatabaseCluster
cluster.add_rotation_multi_user("MyUser",
secret=my_imported_secret
)
```
It's also possible to create user credentials together with the cluster and add rotation:
```python
# cluster: docdb.DatabaseCluster
my_user_secret = docdb.DatabaseSecret(self, "MyUserSecret",
username="myuser",
master_secret=cluster.secret
)
my_user_secret_attached = my_user_secret.attach(cluster) # Adds DB connections information in the secret
cluster.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](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/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`:
```python
import aws_cdk.aws_iam as iam
import aws_cdk.aws_logs as logs
# my_logs_publishing_role: iam.Role
# vpc: ec2.Vpc
cluster = docdb.DatabaseCluster(self, "Database",
master_user=docdb.Login(
username="myuser"
),
instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
vpc_subnets=ec2.SubnetSelection(
subnet_type=ec2.SubnetType.PUBLIC
),
vpc=vpc,
export_profiler_logs_to_cloud_watch=True, # Enable sending profiler logs
export_audit_logs_to_cloud_watch=True, # Enable sending audit logs
cloud_watch_logs_retention=logs.RetentionDays.THREE_MONTHS, # Optional - default is to never expire logs
cloud_watch_logs_retention_role=my_logs_publishing_role
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-docdb",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/99/89/da262fe60b240969dc9347c1319496aef83be7a7d70154f2c1b337be4aea/aws-cdk.aws-docdb-1.203.0.tar.gz",
"platform": null,
"description": "# Amazon DocumentDB Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\n## Starting a Clustered Database\n\nTo set up a clustered DocumentDB database, define a `DatabaseCluster`. You must\nalways launch a database in a VPC. Use the `vpcSubnets` attribute to control whether\nyour instances will be launched privately or publicly:\n\n```python\n# vpc: ec2.Vpc\n\ncluster = docdb.DatabaseCluster(self, \"Database\",\n master_user=docdb.Login(\n username=\"myuser\", # NOTE: 'admin' is reserved by DocumentDB\n exclude_characters=\"\\\"@/:\", # optional, defaults to the set \"\\\"@/\" and is also used for eventually created rotations\n secret_name=\"/myapp/mydocdb/masteruser\"\n ),\n instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),\n vpc_subnets=ec2.SubnetSelection(\n subnet_type=ec2.SubnetType.PUBLIC\n ),\n vpc=vpc\n)\n```\n\nBy default, the master password will be generated and stored in AWS Secrets Manager with auto-generated description.\n\nYour cluster will be empty by default.\n\n## Connecting\n\nTo control who can access the cluster, use the `.connections` attribute. DocumentDB databases have a default port, so\nyou don't need to specify the port:\n\n```python\n# cluster: docdb.DatabaseCluster\n\ncluster.connections.allow_default_port_from_any_ipv4(\"Open to the world\")\n```\n\nThe endpoints to access your database cluster will be available as the `.clusterEndpoint` and `.clusterReadEndpoint`\nattributes:\n\n```python\n# cluster: docdb.DatabaseCluster\n\nwrite_address = cluster.cluster_endpoint.socket_address\n```\n\nIf you have existing security groups you would like to add to the cluster, use the `addSecurityGroups` method. Security\ngroups added in this way will not be managed by the `Connections` object of the cluster.\n\n```python\n# vpc: ec2.Vpc\n# cluster: docdb.DatabaseCluster\n\n\nsecurity_group = ec2.SecurityGroup(self, \"SecurityGroup\",\n vpc=vpc\n)\ncluster.add_security_groups(security_group)\n```\n\n## Deletion protection\n\nDeletion protection can be enabled on an Amazon DocumentDB cluster to prevent accidental deletion of the cluster:\n\n```python\n# vpc: ec2.Vpc\n\ncluster = docdb.DatabaseCluster(self, \"Database\",\n master_user=docdb.Login(\n username=\"myuser\"\n ),\n instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),\n vpc_subnets=ec2.SubnetSelection(\n subnet_type=ec2.SubnetType.PUBLIC\n ),\n vpc=vpc,\n deletion_protection=True\n)\n```\n\n## Rotating credentials\n\nWhen the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:\n\n```python\n# cluster: docdb.DatabaseCluster\n\ncluster.add_rotation_single_user()\n```\n\n```python\ncluster = docdb.DatabaseCluster(stack, \"Database\",\n master_user=docdb.Login(\n username=\"docdb\"\n ),\n instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),\n vpc=vpc,\n removal_policy=cdk.RemovalPolicy.DESTROY\n)\n\ncluster.add_rotation_single_user()\n```\n\nThe multi user rotation scheme is also available:\n\n```python\nimport aws_cdk.aws_secretsmanager as secretsmanager\n\n# my_imported_secret: secretsmanager.Secret\n# cluster: docdb.DatabaseCluster\n\n\ncluster.add_rotation_multi_user(\"MyUser\",\n secret=my_imported_secret\n)\n```\n\nIt's also possible to create user credentials together with the cluster and add rotation:\n\n```python\n# cluster: docdb.DatabaseCluster\n\nmy_user_secret = docdb.DatabaseSecret(self, \"MyUserSecret\",\n username=\"myuser\",\n master_secret=cluster.secret\n)\nmy_user_secret_attached = my_user_secret.attach(cluster) # Adds DB connections information in the secret\n\ncluster.add_rotation_multi_user(\"MyUser\", # Add rotation using the multi user scheme\n secret=my_user_secret_attached)\n```\n\n**Note**: This user must be created manually in the database using the master credentials.\nThe rotation will start as soon as this user exists.\n\nSee 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.\n\n## Audit and profiler Logs\n\nSending audit or profiler needs to be configured in two places:\n\n1. 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\n [profiler](https://docs.aws.amazon.com/documentdb/latest/developerguide/profiling.html#profiling.enable-profiling) logs.\n2. Enable the corresponding option(s) when creating the `DatabaseCluster`:\n\n```python\nimport aws_cdk.aws_iam as iam\nimport aws_cdk.aws_logs as logs\n\n# my_logs_publishing_role: iam.Role\n# vpc: ec2.Vpc\n\n\ncluster = docdb.DatabaseCluster(self, \"Database\",\n master_user=docdb.Login(\n username=\"myuser\"\n ),\n instance_type=ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),\n vpc_subnets=ec2.SubnetSelection(\n subnet_type=ec2.SubnetType.PUBLIC\n ),\n vpc=vpc,\n export_profiler_logs_to_cloud_watch=True, # Enable sending profiler logs\n export_audit_logs_to_cloud_watch=True, # Enable sending audit logs\n cloud_watch_logs_retention=logs.RetentionDays.THREE_MONTHS, # Optional - default is to never expire logs\n cloud_watch_logs_retention_role=my_logs_publishing_role\n)\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::DocDB",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d7f05edfa7d3c693e1c940c7b41e31c42d511e2cbe9c70e713c4c75bdbb26029",
"md5": "54bc3b5c4c25d6305945dbbb21c1b47f",
"sha256": "d18fc76731480bba502f9542588a6f988d722331eb38666e23502b5968b6e147"
},
"downloads": -1,
"filename": "aws_cdk.aws_docdb-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54bc3b5c4c25d6305945dbbb21c1b47f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 160909,
"upload_time": "2023-05-31T22:54:22",
"upload_time_iso_8601": "2023-05-31T22:54:22.146340Z",
"url": "https://files.pythonhosted.org/packages/d7/f0/5edfa7d3c693e1c940c7b41e31c42d511e2cbe9c70e713c4c75bdbb26029/aws_cdk.aws_docdb-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9989da262fe60b240969dc9347c1319496aef83be7a7d70154f2c1b337be4aea",
"md5": "4e0a8795a3bd1dfe09525394bbf268b2",
"sha256": "b1a4993e4f95d730c896411955aab5173aabfacbdeddb85f4d2e7334be596a0b"
},
"downloads": -1,
"filename": "aws-cdk.aws-docdb-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "4e0a8795a3bd1dfe09525394bbf268b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 162392,
"upload_time": "2023-05-31T23:01:56",
"upload_time_iso_8601": "2023-05-31T23:01:56.785214Z",
"url": "https://files.pythonhosted.org/packages/99/89/da262fe60b240969dc9347c1319496aef83be7a7d70154f2c1b337be4aea/aws-cdk.aws-docdb-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:01:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-docdb"
}
JSON
