Skip to content

Commit

Permalink
docs(rds): improve docs about serverless v1 (#30316)
Browse files Browse the repository at this point in the history 
### 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*
  • Loading branch information
@mazyu36
mazyu36 authored May 24, 2024
1 parent 4857239 commit 58b024d
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 21 deletions.
30 changes: 16 additions & 14 deletions packages/aws-cdk-lib/aws-rds/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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;
Expand All @@ -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'];
```
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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.

Expand Down Expand Up @@ -1198,15 +1200,15 @@ 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.

If not provided, the cluster will be created in the default VPC of the account and region.
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.
Expand Down
14 changes: 7 additions & 7 deletions packages/aws-cdk-lib/aws-rds/lib/serverless-cluster.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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 {
/**
Expand All @@ -527,7 +527,7 @@ export interface ServerlessClusterProps extends ServerlessClusterNewProps {
}

/**
* Create an Aurora Serverless Cluster
* Create an Aurora Serverless v1 Cluster
*
* @resource AWS::RDS::DBCluster
*
Expand Down Expand Up @@ -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
*/
Expand Down

0 comments on commit 58b024d

Please sign in to comment.