From 58b024d529dfb20c8df4bd70b50d00c43f31210d Mon Sep 17 00:00:00 2001 From: mazyu36 Date: Sat, 25 May 2024 02:00:33 +0900 Subject: [PATCH] docs(rds): improve docs about serverless v1 (#30316) ### Issue # (if applicable) Closes #30309. ### Reason for this change The rds.ServerlessCluster is for Serverless v1, but this is not explicitly stated in the documentation, which could be misleading as it may imply that it is for Serverless v2. ### Description of changes Added to the README and TSdocs that rds.ServerlessCluster is for v1 of Aurora Serverless ### Description of how you validated changes Do nothing because only documentation improvements ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- packages/aws-cdk-lib/aws-rds/README.md | 30 ++++++++++--------- .../aws-rds/lib/serverless-cluster.ts | 14 ++++----- 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/packages/aws-cdk-lib/aws-rds/README.md b/packages/aws-cdk-lib/aws-rds/README.md index 0dd960de42733..973762247098e 100644 --- a/packages/aws-cdk-lib/aws-rds/README.md +++ b/packages/aws-cdk-lib/aws-rds/README.md @@ -182,7 +182,7 @@ cluster.metricACUUtilization({ There are some things to take into consideration with Aurora Serverless v2. To create a cluster that can support serverless v2 instances you configure a -minimum and maximum capacity range on the cluster. This is an example showing +minimum and maximum capacity range on the cluster. This is an example showing the default values: ```ts @@ -491,7 +491,7 @@ const gp3Instance = new rds.DatabaseInstance(this, 'Gp3Instance', { }); ``` -Use the `allocatedStorage` property to specify the amount of storage (in gigabytes) that is initially allocated for the instance +Use the `allocatedStorage` property to specify the amount of storage (in gigabytes) that is initially allocated for the instance to use for the instance: ```ts @@ -972,7 +972,7 @@ new rds.DatabaseCluster(this, 'dbcluster', { ## Creating a Database Proxy Amazon RDS Proxy sits between your application and your relational database to efficiently manage -connections to the database and improve scalability of the application. Learn more about at [Amazon RDS Proxy](https://aws.amazon.com/rds/proxy/). +connections to the database and improve scalability of the application. Learn more about at [Amazon RDS Proxy](https://aws.amazon.com/rds/proxy/). RDS Proxy is supported for MySQL, MariaDB, Postgres, and SQL Server. @@ -1016,7 +1016,7 @@ const cluster = new rds.DatabaseCluster(this, 'Database', { // ... }); -// When 'cloudwatchLogsExports' is set, each export value creates its own log group in DB cluster. +// When 'cloudwatchLogsExports' is set, each export value creates its own log group in DB cluster. // Specify an export value to access its log group. const errorLogGroup = cluster.cloudwatchLogGroups['error']; const auditLogGroup = cluster.cloudwatchLogGroups.audit; @@ -1032,7 +1032,7 @@ const instance = new rds.DatabaseInstance(this, 'Instance', { // ... }); -// When 'cloudwatchLogsExports' is set, each export value creates its own log group in DB instance. +// When 'cloudwatchLogsExports' is set, each export value creates its own log group in DB instance. // Specify an export value to access its log group. const postgresqlLogGroup = instance.cloudwatchLogGroups['postgresql']; ``` @@ -1108,14 +1108,14 @@ new rds.DatabaseInstance(this, 'Database', { You cannot specify a parameter map and a parameter group at the same time. -## Serverless +## Serverless v1 -[Amazon Aurora Serverless](https://aws.amazon.com/rds/aurora/serverless/) is an on-demand, auto-scaling configuration for Amazon +[Amazon Aurora Serverless v1](https://aws.amazon.com/rds/aurora/serverless/) is an on-demand, auto-scaling configuration for Amazon Aurora. The database will automatically start up, shut down, and scale capacity up or down based on your application's needs. It enables you to run your database in the cloud without managing any database instances. -The following example initializes an Aurora Serverless PostgreSql cluster. +The following example initializes an Aurora Serverless v1 PostgreSql cluster. Aurora Serverless clusters can specify scaling properties which will be used to automatically scale the database cluster seamlessly based on the workload. @@ -1137,7 +1137,9 @@ const cluster = new rds.ServerlessCluster(this, 'AnotherCluster', { }); ``` -Aurora Serverless Clusters do not support the following features: +**Note**: The `rds.ServerlessCluster` class is for Aurora Serverless v1. If you want to use Aurora Serverless v2, use the `rds.DatabaseCluster` class. + +Aurora Serverless v1 Clusters do not support the following features: * Loading data from an Amazon S3 bucket * Saving data to an Amazon S3 bucket @@ -1152,9 +1154,9 @@ Aurora Serverless Clusters do not support the following features: * Performance Insights * RDS Proxy -Read more about the [limitations of Aurora Serverless](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless.html#aurora-serverless.limitations) +Read more about the [limitations of Aurora Serverless v1](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless.html#aurora-serverless.limitations) -Learn more about using Amazon Aurora Serverless by reading the [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless.html) +Learn more about using Amazon Aurora Serverless v1 by reading the [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless.html) Use `ServerlessClusterFromSnapshot` to create a serverless cluster from a snapshot: @@ -1167,7 +1169,7 @@ new rds.ServerlessClusterFromSnapshot(this, 'Cluster', { }); ``` -### Data API +## Data API You can access your Aurora DB cluster using the built-in Data API. The Data API doesn't require a persistent connection to the DB cluster. Instead, it provides a secure HTTP endpoint and integration with AWS SDKs. @@ -1198,7 +1200,7 @@ cluster.grantDataApiAccess(fn); To learn more about using the Data API, see the [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html). -### Default VPC +## Default VPC The `vpc` parameter is optional. @@ -1206,7 +1208,7 @@ If not provided, the cluster will be created in the default VPC of the account a As this VPC is not deployed with AWS CDK, you can't configure the `vpcSubnets`, `subnetGroup` or `securityGroups` of the Aurora Serverless Cluster. If you want to provide one of `vpcSubnets`, `subnetGroup` or `securityGroups` parameter, please provide a `vpc`. -### Preferred Maintenance Window +## Preferred Maintenance Window When creating an RDS cluster, it is possible to (optionally) specify a preferred maintenance window for the cluster as well as the instances under the cluster. See [AWS docs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#Concepts.DBMaintenance) for more information regarding maintenance windows. diff --git a/packages/aws-cdk-lib/aws-rds/lib/serverless-cluster.ts b/packages/aws-cdk-lib/aws-rds/lib/serverless-cluster.ts index 418d7ae347048..df16ac81933c7 100644 --- a/packages/aws-cdk-lib/aws-rds/lib/serverless-cluster.ts +++ b/packages/aws-cdk-lib/aws-rds/lib/serverless-cluster.ts @@ -50,7 +50,7 @@ export interface IServerlessCluster extends IResource, ec2.IConnectable, secrets grantDataApiAccess(grantee: iam.IGrantable): iam.Grant; } /** - * Common Properties to configure new Aurora Serverless Cluster or Aurora Serverless Cluster from snapshot + * Common Properties to configure new Aurora Serverless v1 Cluster or Aurora Serverless v1 Cluster from snapshot */ interface ServerlessClusterNewProps { /** @@ -98,7 +98,7 @@ interface ServerlessClusterNewProps { readonly enableDataApi?: boolean; /** - * The VPC that this Aurora Serverless cluster has been created in. + * The VPC that this Aurora Serverless v1 Cluster has been created in. * * @default - the default VPC in the account and region will be used */ @@ -260,7 +260,7 @@ export enum TimeoutAction { } /** - * Options for configuring scaling on an Aurora Serverless cluster + * Options for configuring scaling on an Aurora Serverless v1 Cluster * */ export interface ServerlessScalingOptions { @@ -387,7 +387,7 @@ abstract class ServerlessClusterBase extends Resource implements IServerlessClus } /** - * Create an Aurora Serverless Cluster + * Create an Aurora Serverless v1 Cluster * * @resource AWS::RDS::DBCluster */ @@ -508,7 +508,7 @@ abstract class ServerlessClusterNew extends ServerlessClusterBase { } /** - * Properties for a new Aurora Serverless Cluster + * Properties for a new Aurora Serverless v1 Cluster */ export interface ServerlessClusterProps extends ServerlessClusterNewProps { /** @@ -527,7 +527,7 @@ export interface ServerlessClusterProps extends ServerlessClusterNewProps { } /** - * Create an Aurora Serverless Cluster + * Create an Aurora Serverless v1 Cluster * * @resource AWS::RDS::DBCluster * @@ -709,7 +709,7 @@ export interface ServerlessClusterFromSnapshotProps extends ServerlessClusterNew } /** - * A Aurora Serverless Cluster restored from a snapshot. + * A Aurora Serverless v1 Cluster restored from a snapshot. * * @resource AWS::RDS::DBCluster */