docs(rds): clarify how to enable S3Import/S3Export in Readme.md

[duranbe]

Reason for this change

Documentation does not state clearly that feature needs to be manually enabled when using Postgres

Example :
The following code will fail with the error message

const cluster = new rds.DatabaseCluster(this, 'Database', {
      engine: rds.DatabaseClusterEngine.auroraPostgres({version: AuroraPostgresEngineVersion.of('12.7','12')}),
      writer: rds.ClusterInstance.provisioned('writer', {
        instanceType: ec2.InstanceType.of(ec2.InstanceClass.R6G, ec2.InstanceSize.XLARGE4),
      }),
      serverlessV2MinCapacity: 6.5,
      serverlessV2MaxCapacity: 64,
      s3ImportRole: sampleRole
});

Will fail with this error message :Error: s3Import is not supported for Postgres version: 12.7. Use a version that supports the s3Import feature

But the thing is that 12.7 does support it ! The real problem here is that the feature needs to be enabled as such

const cluster = new rds.DatabaseCluster(this, 'Database', {
      engine: rds.DatabaseClusterEngine.auroraPostgres({version: AuroraPostgresEngineVersion.of('12.7','12', {s3Export: true, s3Import:true})}),
      writer: rds.ClusterInstance.provisioned('writer', {
        instanceType: ec2.InstanceType.of(ec2.InstanceClass.R6G, ec2.InstanceSize.XLARGE4),
      }),
      serverlessV2MinCapacity: 6.5,
      serverlessV2MaxCapacity: 64,
      s3ImportRole: sampleRole
});

Description of changes

Small update to Readme.md and inline TSdoc

Description of how you validated changes

None

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter has failed. See the aws-cdk-automation comment below for failure reasons. If you believe this pull request should receive an exemption, please comment and provide a justification.

A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed add Clarification Request to a comment.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[aaythapa]

Hi, thanks for making this change! Is there any documentation that supports this claim? Just want to make sure before approving

[duranbe]

Hello !
Sure I can, here is the AWS Doc for S3Import, that mentions this feature to choose from.

As well, here is the relevant code that checks if the S3Import/S3Export feature has been enabled, which by default is false

https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-rds/lib/cluster-engine.ts#L1061

Actually now that I think of it, the error message s3Import is not supported for Postgres version: ${this.engineVersion.fullVersion}. Use a version that supports the s3Import feature. is a bit misleading as the issue could also be not having enabled the feature when declaring the DatabaseClusterEngine

[scanlonp]

Hey @duranbe, quick note. Our doc generation has some odd behavior with respect to tags (@see, @default, etc.). Any text after a tag will be omitted. Only the last @see link will be used.

Take a look at s3ExportRole in our docs (link). You'll see that 'For PostgreSQL:' does not show up. Also the link is the PostgreSQL link (the last one).

While this problem is widespread in the file, you should be good only fixing the formatting for these two props. That should help your changes to actually show up!

[duranbe]

Hey @scanlonp - thanks for the advice, indeed this is a odd behavior, I modified as I expect to render. Is there a way to build locally the doc ? I might have missed it in the contributing guide

[evzzk]

What is the 'respectives' feature? Having trouble finding out more information about it.

[duranbe]

It refer to the s3Import and s3Export features

this._features = {
      s3Import: auroraPostgresFeatures?.s3Import ? 's3Import' : undefined,
      s3Export: auroraPostgresFeatures?.s3Export ? 's3Export' : undefined,
    };

https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/postgresql-s3-export.html#:~:text=Under%20Feature%2C%20choose%20s3Export.

[duranbe]

Feel free to rephrase - good to have an external view

[evzzk]

Is it accurate to say this?

To use s3ImportRole and s3ExportRole with Aurora PostgreSQL, you must also configure the S3 import and export features when creating the DatabaseClusterEngine.

[duranbe]

I think enable would be more appropriate - as it is turning a boolean flag to true

[duranbe]

I updated the PR with an example - it might also make sense to update the error message

[duranbe]

Updated after comments 🙌

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 179375b
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[duranbe]

Good on my side 👍